TKpopMenu creates popUp menus from unlimited TEXT resources, or from a HyperCard‚Ñ¢ container, or from real MENU resources. Supports hierarchical menus, ICONS, reduced ICONs, SICNs (small icons), special FONT, FONT Size, and resource menus. It will also create PICTure type menus.
ÊÊflget TKpopMenu("Animals",left of me,bottom of me)
ÊÊflget TKpopMenu("Animals",the mouseH, the mouseV)
ÊÊflget TKpopMenu("XCMDs,
"&return,"","","true")
Parameters
Ó›get TKpopMenu ("myMenu")
Parameter 1
name: name of menu resource for the appropriate type of menu (TEXT, PICT, MENU). If this is left empty then it is assumed the item list is literal and passed in the 5th parameter.
Ó›get TKpopMenu ("myMenu", left of me + 1)
Parameter 2
LEFT: left postition of menu. If it is "" then the default is left of target
Ó›get TKpopMenu ("myMenu", left of me + 1, bottom of me)
Parameter 3
TOP: top position of menu. If it is "" then the default is bottom of target
Parameter 4
cmd: a list of the following appropriate commands, separated by commas, and enclosed in quotes. Not case sensitive.
For TEXT menus:
 menu: specify use of a MENU type resource of the specified
    fi‹name in parameter 1
 sort: sort the item list
For PICT menus:
Ó›get "pict,across3,down1,cellH75,cellW75,loc"
 fl€Get TKpopMenu("pMenu",left of me - 1,bottom of me - 1,it)
 pict: specify use of a PICT type resource of the specified
   fl›name in parameter 1
 across + number: how many PICT menu cells across
 down + number: how many PICT menu cells down
 cellH + number: height of each cell
 cellW + number: width of each cell
For ALL menus:
 loc: use local coordinates.
Parameter 5
itemList: This is the item list from a HyperCard‚Ñ¢ container. It is useful for modifying the item list before the menu is shown. For instance, you can fetch a basic item list from a TEXT resource using TKdoTEXT, modify it by enabling/disabling items, adding check marks, etc. and then passing the list to TKpopMenu.
ÓÊTKpopMenu has no special requirements that would provoke the dreaded ı. If the item list is missing you will get a "Beep" when you try to use the menu and if any ICONs or SICNs required in the menu are missing they simply will not show up on the menu.
ÓÊTKpopMenu MUST be used in a mouseDOWN handler because menu handling is performed when the user clicks and holds the mouse button DOWN.
ÓÊThere are a couple of unique features in this XFCN. First, you do not normally pass an item list to this XFCN. Instead, you pass the name of a TEXT resource in the stack.
Secondly, TKpopMenu returns what you select. That means you will not have to modify your handler for the menu items if you edit the item list.
Another unique feature is the ability to create a menu list of ANY resource type in your stack. For instance:
ÊÊÊTEXT,
you will get a hierarchical menu item called TEXT with a sorted submenu of all the 'TEXT' resources in the stack. That strange looking character (the box) following the comma is option/shift 'R' for Resource.
• PICT Type Menus
ÈÊTKpopMenu allows you to create PICTure type menus. This is done by sending certain specifiers to TKpopMenu. A PICT type menu consists of a number of cells, all of which must be equal in size. They do NOT have to be square, that is, equal on all sides. Rectangles are permitted, but, they all must be the same size. The only limit to the number of cells is a practical one which is the screen size. The steps to using these menus are as follows:
1. Create a graphic (picture) of the menu the way you want to see it. The PICT should be composed of a number of equal sized cells, or rectangles. Color the PICT if you want.
2. Copy the inner contents of the PICTure and store it as a PICT resource in your stack. Remember, the menu itself will frame the picture, so, you want to copy the contents of the PICTure just inside the overall border of your PICTure. Make sure the PICT resource has a name.
3. Now you can call TKpopMenu with the following specifiers:
PICT,ACROSSn,DOWNn,CELLWn,CELLHn where
PICT commands TKpopMenu to create a PICT type menu
ACROSSn specifies n cells ACROSS
DOWNn specifies n cells DOWN
CELLWn specifies cells of n width (actual outside width - 1)
CELLHn specifies cells of n height (actual outside height - 1)
The commands are not case sensitive and the commas are not necessary.
ʈÊCLICK HERE to see an illustration of this.
 m CLICK AND HOLD to see Menu1
The script might look like this:
on mouseDown
get "pict,across3,down1,cellw124,cellh124"
get TKpopMenu("myPICTname","","",it)
if it = "" then exit to hyperCard
if it = 1 then
-- process "No Preppies"
else if it = 2 then
-- process "No Smoking"
else if it = 3 then
-- process "No Nukes"
end if
end mouseDown
ÓÊWhat is returned is the number of the cell selected, from left to right and top to bottom.
ÈÊYou can use two or more menu PICTs to show some intermediate result. The PhoneBook stack provided with ToolKit™ illustrates this. One of the things the control menu allows you to do is insert notes for any given name. If no notes exist the menu appears with an empty document representing the hidden note field for a name. This is illustrated by the following example:
 m CLICK AND HOLD to see Menu2
Once notes are posted to a name the menu will have a document with writing in it, like this:
 m CLICK AND HOLD to see Menu3
The name of the PICT to use is simply changed as according to the contents of the field used to hold notes. The part of the script that does this looks like this:
•
•
get "pict,across3,down1,cellH75,cellW75"
if bg fld "Notes" = "" then
get TKpopMenu("Menu1","","",it)
else
get TKpopMenu("Menu2","","",it)
end if
•
•
More Information
ÓÊMeta-characters are special characters inserted before items that allow the display of ICONs, SICNs, different font styles, cmd key equivalents. Meta-characters are always followed by another character to further define the modification.
TKpopMenu goes beyond the toolbox. Suppose we wanted a list of all ICONs and XCMDs to show up in a hierarchical menu.
ÊÊÊÊÊICONs,
ÊÊÊÊÊXCMDx,
The little box following each item is an option/shift "R" (for 'Resource'). It directs TKpopMenu to build a sorted submenu of all available resources of the specified type IN THE CURRENT STACK.
The first four characters of the menu item MUST match EXACTLY the name of a class of resources (ie. Icon is not ICON). It is case sensitive. Resource types are always four characters long. TKpopMenu does not care what follows the first four characters (notice the small "s" after ICON). The option/shift 'R' tells TKpopMenu to compile a SORTED list of all the resources of type ICON into a hierarchical submenu.
See Inside Macintosh‚Ñ¢ volume 1 page 107 for information on resource types.
• Fonts
Fonts are a special case:
ÊÊÊÊÊFONTs,
The little box here is an option/shift "F" because we want TKpopMenu to build a menu of ALL available FONTs including the System, HyperCard, Home, and the current stack. Option/shift "R" would only show fonts in the current stack.
Another unique TKpopMenu feature is FONT sizes.
ÊÊÊÊÊSize,
The "special character" in this case is an option/shift "S". This will create a size menu for fonts and outline the sizes available for the currently selected font.
